MacWorld 1998 March

home *** CD-ROM | disk | FTP | other *** search

/ MacWorld 1998 March / Macworld (1998-03) (Disk 1).dmg / Shareware World / Utilities / Text Processing / Alpha / Help / BibTeX Help < prev next >

Wrap

Text File | 1997-07-31 | 19.4 KB | 476 lines | [TEXT/ALFA]

##################### BibTeX mode for Alpha ##################### This document describes features of Bib mode and the BibTeX menu, which were written to simplify the use and maintenance of BibTeX citation database files. Bib Mode ======== Bib mode is entered when you open a file with a '.bib' suffix, or when select the mode explicitly from the modes menu. In Bib mode, • A BibTeX menu is added to the menubar. Commands available from this menu are summarized in the next section below. • Selecting 'Mark File' in the Marks menu, "{}" on the sidebar, will add an index mark for the cite-key of each entry in the bib file. Marks are added in order of appearance in the file. To order them alphabetically, use the "Sort Marks…:Alphabetically" command on the Bibtex menu. • Key words in Bib files are automatically colorized. • Double-clicking on an abbreviation string with the command key held down ("command-double-clicking") will move the cursor to the definition of that abbreviation. • Command-double-clicking on the cite-key of a "crossref" field will move the cursor to the referenced entry. BibTeX menu =========== Here's a description of the commands available from the BibTeX menu: (key bindings are indicated where available) BibTeX interaction ------------------ Bibtex Switch to the BibTeX application (launching it if necessary). Template insertion ------------------ Entries > Insert a template for any of the various BibTeX bibliography entry types (as in Tex mode). By default, only the required fields an the entry are included in the template. This can be customized as described below. Choosing "Custom Entry" lets you pick the fields to be included from a list of all fields. Fields > Insert a template for any of the various BibTeX bibliography data fields. Choosing "Custom Field" inserts a template without a pre-written field name. Choosing "Multiple Fields" lets you pick the a number fields to be included at once. Entry Navigation, etc. ---------------------- Select Entry Select (highlight) the current entry (in which the cursor sits), allowing the entry to be easily moved, copied or deleted. (Ctl-Shift-B) Next Entry Jump to the top of the next entry. (Ctl-Shift-N) Prev Entry Jump to the top of the previous entry. (Ctl-Shift-P) Format Entry Reformat the current entry in a standard form, with data fields indented and aligned, and data-field delimiters made uniform. (Ctl-Shift-L) Afterwards, Alpha jumps forward to the next entry, so you can keep hitting Ctl-Shift-L to reformat a number of entries in a row. The format may be customized using the formatting flags and variables in the flags menu ("√" on the sidebar). Copy Cite Key Copy the cite key for the current entry to the clipboard Sorting and Searching --------------------- Search Entries Search for entries that match a given regular expression. (Ctl-Shift-M) Search Fields Search for entries in which a particular field matches a regular expression. (Ctl-Shift-F) Entries found in a search will be copied to a new window (the default) or back into the original buffer, replacing the previous contents of the buffer; this is controlled by the "overwriteBuffer" mode flag. Sort by… > Sort the database by one of various criteria... Cite Key Sort by the citatation key First Author, Year Sort by first or last author, and secondarily by year Last Author, Year Year, First Author Sort by year, and secondarily by first or last author Year, Last Author The "overwriteBuffer" mode flag also controls whether the sorted database is written back to the original buffer or into a new one. Sort Marks… > Alphabetically Sort the index marks on the marks menu alphabetically. By Position Sort the index marks by the position of the entry. Other ----- Count Entries Report the total number of entries, as well the number of entries of each type. Format All Entries Reformat the current entry and all subsequent entries to end of the file. You can interrupt this by hitting the "Cmd-." key Mode Flags and Variables ======================== The behavior of the Bibtex menu may be controlled using by setting the various flags and variables in the flags menu ("√") on the sidebar. These are... …For Entry Formatting --------------------- alignEquals Line up the "=" signs for all fields when reformatting entryBraces Use curly braces to delimit entries (otherwise parentheses are used). fieldBraces Use curly braces to delimit field values (otherwise quotation marks are used). zapEmptyFields Remove optional fields if they're empty. fillColumn The maximum width of each line in the field value. indentString Define the indentation string for field names. stdAbbrevs Define standard abbreviations (which we avoid surrounding with delimiters) that do not appear in @string entries. By default, the three-letter English month names are included. …For Sorting and Searching -------------------------- overwriteBuffer Allow sorts and searches to replace the original window contents. (Otherwise they are written to a new window.) Note: The contents of a ".bib" file, will never be overwritten by a search, since entries are typically lost. A ".bib" file _can_ be overwritten by a sort, since no entries are lost. descendingYears Sort by year in descending order (most recent to oldest) markStrings Include @string definitions in the marks menu. segregateStrings Collect all @string definitions together at the top of the file in sorts. (Otherwise sort alphabetically) Key Bindings ============ Most of these functions (except template insertion) are also bound to keystrokes. The standard bindings are Ctl-Shift-N next entry Ctl-Shift-P previous entry Ctl-Shift-B select entry Ctl-Shift-L format entry Ctl-Shift-M search entries Ctl-Shift-F search fields tab next tab stop (as in TeX mode) Shift-tab previous tab stop ( " " " " ) Ctl-tab nth tab stop ( " " " " ) Cmd-tab clear tab stop ( " " " " ) Opt-tab insert a real tab ( " " " " ) Although the TeX-mode keybindings aren't available in Bib mode, the LaTeX menu is left on the menubar. This may be useful for inserting the various text-style codes that are recognized in BibTeX fields. Customizing Entry Templates =========================== Only the required fields are included by default when a new bib entry is created. You can select any other set of fields by adding an appropriate entry to the 'myFld' array, following the example for the Article entry in the file ":SystemCode:bibtex.tcl", accessible through the Filesets menu. Some day I'll make it easier to customize this, but for now it's necessary to modify bibtex.tcl. You should _not_ change the 'rqdFld' or 'optFld' arrays, since these will (some day) be used for syntax checking. Bugs, etc. ========== Bug reports, complaints and suggestions are very welcome. Most of the improvements and bug fixes made since the last major release (2.0) were the result of reports and suggestions from users. Reports can be directed to the author at Tom Pollard <pollard@cucbs.chem.columbia.edu> You can also send mail to Tom Scavo (trscavo@syr.edu> or Pete Keleher <keleher@cs.umd.edu> and they'll forward your comments to me. Version History --------------- 2.7 (7/95) 'stdAbbrevs' modeVar added for setting predefined abbrevs month names included as predefined abbrevs 'alignEquals' formatting flag added. 2.62 (7/95) field delimiters suppressed if field data is an abbreviation unindexed .bib files are indexed automatically upon opening 2.61 (7/95) fixed "SearchFields" bug. 2.6 (6/95) 'zapEmptyFields' flag forces optional fields to be removed when reformatting an entry. 'markStrings' flag controls whether @string entries are included in the marks menu. 'descendingYears' flag controls whether sorts are in ascending or descending chronological order. Sorts all use the year as either primary or secondary sort key now. 'copyCiteKey' command copies the citekey of the current entry to the clipboard. Cmd-double-clicking implemented to resolve abbreviations and crossrefs. Fixed bug in faster getFields proc (comma-after-last-field problems) Fixed minor bugs in author sorting. 2.5 (6/95) Fixed bug in formatEntry, whereby '#' concatenations were lost formatEntry completely ignores @string entries now Entry-parsing code (getFields, getFldVal) cleaned up, should also be a little bit faster now. formatAllEntries now starts working from the current entry 2.41 (6/95) Updates for compatibility with revised LaTeX mode Automatic conversion of international characters dropped (irreconcilable problems with non-US keyboards). 2.4 (5/95) Fixed bugs in parsing of EndNote-created bib files 2.3 (4/95) International characters converted to TeX codes (optionally). 'findEntries' bug fixed (no longer returns multiple hits) 2.2 (12/94) 'formatEntries' won't quote fields that contain "#". 'segregateStrings' flag forces string defs to sort to the top. 2.11(12/94) Bug fixes in 'formatAllEntries'. 2.1 (12/94) 'countEntries' command added. 'formatAllEntries' command added; it's a bit clunky, but more robust than any quicker alternative I considered. Cross-referenced entries now sort to the bottom in all sorts. 'crossref' field now included. 2.0 (9/94) 'formatEntry' and 'newEntry' line up fields better. 'nextEntry' and 'prevEntry' skip @string defs 'formatEntry' automtically goes to next entry afterwards. 'sortByCitekey' ignores case of cite keys. 'fillColumn' included as default modeVar. 'getEntry' alerts user to badly delimited entries. 1.9 (9/94) 'getFields' should now correctly parse any legal entry. 'language' field now included. Default values for new fields (eg 'language') may be defined 'preferBraces' replaced by 'fieldBraces' and 'entryBraces'. line-wrapping is done on reformatted entries. '@string' entries preserved in sorts. text before first entry and after last entry are preserved by sorts. 1.8 (8/94) "getEntry" now recognizes parens as entry delimiters 1.7 (8/94) Bug fixes and accomodations to latex.tcl v2.2 Template insertion streamlined Choose multiple fields at a time from a list dialog 1.6 (8/94) "preferBraces" allows braces or quotes to be default for new or reformatted entries, Menu built using $entryNames and $fieldNames, 'sortByAuthors' can now sort using last author first, and is a bit faster, 'formatEntry' rewrites entries in canonical format, More customization of canonical format allowed ('indentString') Bib mode definition adapted to Alpha 5.90. 1.5 (7/94) "sortByAuthors" is now robust, Mode of new windows now set correctly. 1.4 (7/94) Added sorting by authors, but still only semi-functional, Added regexp searching by field, "getEntry" bugs fixed. 1.2 (7/94) Bib mode definition adapted to Alpha 5.85, Added bib-file marking (bibMarkFile), Entry and field creation now controlled by data arrays. 1.1 (6/94) Custom BibTeX icon, Added simple search capability (matchingEntries). 1.0 (9/93) First stable version. Future Directions ----------------- These are come of the ideas I'm considering for future enhancements to the BibTeX support package (roughly in the order they're likely to be addressed). I welcome any comments or additional ideas people may have. 1. Some sort of consistency and/or syntax checking of the database; for instance, verifying that all entries have the required fields and checking for duplicate entries. 2. Speed up entry reformatting 3. Allowing the user to interactively choose the standard fields used for a given entry type. 4. Allowing more complicated searches. Logical 'AND' searches can be done now by doing additional searches on the results of previous ones. It would be nice to allow logical 'OR' searches by concatenating the results of successive searches to a database in the same buffer. Ideas for simple, intuitive ways to control this would be welcome. ?. Since the code parses BibTeX entries already, it would be easy to export .bib files to other formats, but I'm not sure if it's a good idea to start burdening Alpha with that sort of thing. Writing Perl scripts for file conversions is probably a better idea. See, for instance, the "CC to BibTeX" Perl script (included in the :Tcl:UserCode:TextFilters folder), which converts citations from the on-line Current Contents database (the one at UC Berkeley, anyway) to BibTeX format. BibTeX application ================== If you don't already have a BibTeX application, version 2.0 of MacBibTeX can found at the following URL ftp://ftp.bluesky.com/ftp-area/pub/utilities/BibTeX.sea.hqx (You can download it by selecting the above URL and running the 'sendURL' command from the' Utils' menu.) MacBibTeX was written by Jim Studt <jim@wucs1.wustl.edu> , and Michael Kahn <kahn@wucs1.wustl.edu> based on Oren Patashnik's original BibTeX 0.99c . Acknowledgments =============== This package was inspired by LaTeX support package (latex.tcl), written by Tom Scavo <trscavo@syr.edu> , and (originally), Richard T. Austin <austin@eecs.umich.edu> --------------------------------------------------------------------------- ########################################################################### # Notes: # # By default, only the required fields are included when a new bib entry # is created. You can select any other set of fields to be used by adding # an appropriate entry to the 'myFld' array, following the example for the # Article entry, further below. You shouldn't change the 'rqdFld' or # 'optFld' arrays, since these will (some day) be used for syntax checking. # ########################################################################### # written by Tom Pollard (pollard@cucbs.chem.columbia.edu) # # Version History # # 2.7 (7/95) 'stdAbbrevs' modeVar added for setting predefined abbrevs # month names included as predefined abbrevs # 'alignEquals' formatting flag added. # 2.62 (7/95) field delimiters suppressed if field data is an abbreviation # unindexed .bib files are indexed automatically upon opening # 2.61 (7/95) fixed "SearchFields" bug. # 2.6 (6/95) 'zapEmptyFields' flag forces optional fields to be removed # when reformatting an entry. # 'markStrings' flag controls whether @string entries are included in # the marks menu. # 'descendingYears' flag controls whether sorts are in ascending or # descending chronological order. # Sorts all use the year as either primary or secondary sort key now. # 'copyCiteKey' command copies the citekey of the current entry to the # clipboard. # Cmd-double-clicking implemented to resolve abbreviations and crossrefs. # Fixed bug in faster getFields proc (comma-after-last-field problems) # Fixed minor bugs in author sorting. # 2.5 (6/95) Fixed bug in formatEntry, whereby '#' concatenations were lost # formatEntry completely ignores @string entries now # Entry-parsing code (getFields, getFldVal) cleaned up, # should also be a little bit faster now. # formatAllEntries now starts working from the current entry # 2.41 (6/95) Updates for compatibility with revised LaTeX mode # Automatic conversion of international characters dropped # (irreconcilable problems with non-US keyboards). # 2.4 (5/95) Fixed bugs in parsing of EndNote-created bib files # 2.3 (4/95) International characters converted to TeX codes (optionally). # 'findEntries' bug fixed (no longer returns multiple hits) # 2.2 (12/94) 'formatEntries' won't quote fields that contain "#". # 'segregateStrings' flag forces string defs to sort to the top. # 2.11(12/94) Bug fixes in 'formatAllEntries'. # 2.1 (12/94) 'countEntries' command added. # 'formatAllEntries' command added; it's a bit clunky, but more robust # than any quicker alternative I considered. # Cross-referenced entries now sort to the bottom in all sorts. # 'crossref' field now included. # 2.0 (9/94) 'formatEntry' and 'newEntry' line up fields better. # 'nextEntry' and 'prevEntry' skip @string defs # 'formatEntry' automtically goes to next entry afterwards. # 'sortByCitekey' ignores case of cite keys. # 'fillColumn' included as default modeVar. # 'getEntry' alerts user to badly delimited entries. # 1.9 (9/94) 'getFields' should now correctly parse any legal entry. # 'language' field now included. # Default values for new fields (eg 'language') may be defined # 'preferBraces' replaced by 'fieldBraces' and 'entryBraces'. # line-wrapping is done on reformatted entries. # '@string' entries preserved in sorts. # text before first entry and after last entry are preserved # by sorts. # 1.8 (8/94) "getEntry" now recognizes parens as entry delimiters # 1.7 (8/94) Bug fixes and accomodations to latex.tcl v2.2 # Template insertion streamlined # Choose multiple fields at a time from list dialog # 1.6 (8/94) "preferBraces" allows braces or quotes to be default for # new or reformatted entries, # Menu built using $entryNames and $fieldNames, # 'sortByAuthors' can now sort using last author first, # and is a bit faster, # 'formatEntry' rewrites entries in canonical format, # More customization of canonical format allowed ('indentString') # Bib mode definition adapted to Alpha 5.90. # 1.5 (7/94) "sortByAuthors" is now robust (I think), # Mode of new windows now set correctly. # 1.4 (7/94) Added sorting by authors, but still only semi-functional, # Added regexp searching by field, # "getEntry" bugs fixed. # 1.2 (7/94) Bib mode definition adapted to Alpha 5.85, # Added bib-file marking (bibMarkFile), # Entry and field creation now controlled by data arrays. # 1.1 (6/94) Custom BibTeX icon, # Added simple search capability (matchingEntries). # 1.0 (9/93) First stable version. # ###########################################################################